<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Flattened datatype | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="mapping-types.html" title="Field datatypes">
<link rel="prev" href="histogram.html" title="Histogram datatype">
<link rel="next" href="geo-point.html" title="Geo-point datatype">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="mapping.html">Mapping</a></span>
»
<span class="breadcrumb-link"><a href="mapping-types.html">Field datatypes</a></span>
»
<span class="breadcrumb-node">Flattened datatype</span>
</div>
<div class="navheader">
<span class="prev">
<a href="histogram.html">« Histogram datatype</a>
</span>
<span class="next">
<a href="geo-point.html">Geo-point datatype »</a>
</span>
</div>
<div class="section xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="flattened"></a>Flattened datatype<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/mapping/types/flattened.asciidoc">edit</a><a class="xpack_tag" href="/subscriptions"></a>
</h2>
</div></div></div>

<p>By default, each subfield in an object is mapped and indexed separately. If
the names or types of the subfields are not known in advance, then they are
<a class="xref" href="dynamic-mapping.html" title="Dynamic Mapping">mapped dynamically</a>.</p>
<p>The <code class="literal">flattened</code> type provides an alternative approach, where the entire
object is mapped as a single field. Given an object, the <code class="literal">flattened</code>
mapping will parse out its leaf values and index them into one field as
keywords. The object’s contents can then be searched through simple queries
and aggregations.</p>
<p>This data type can be useful for indexing objects with a large or unknown
number of unique keys. Only one field mapping is created for the whole JSON
object, which can help prevent a <a class="xref" href="mapping.html#mapping-limit-settings" title="Settings to prevent mappings explosion">mappings explosion</a>
from having too many distinct field mappings.</p>
<p>On the other hand, flattened object fields present a trade-off in terms of
search functionality. Only basic queries are allowed, with no support for
numeric range queries or highlighting. Further information on the limitations
can be found in the <a class="xref" href="flattened.html#supported-operations" title="Supported operations">Supported operations</a> section.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>The <code class="literal">flattened</code> mapping type should <span class="strong strong"><strong>not</strong></span> be used for indexing all
document content, as it treats all values as keywords and does not provide full
search functionality. The default approach, where each subfield has its own
entry in the mappings, works well in the majority of cases.</p>
</div>
</div>
<p>An flattened object field can be created as follows:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT bug_reports
{
  "mappings": {
    "properties": {
      "title": {
        "type": "text"
      },
      "labels": {
        "type": "flattened"
      }
    }
  }
}

POST bug_reports/_doc/1
{
  "title": "Results are not sorted correctly.",
  "labels": {
    "priority": "urgent",
    "release": ["v1.2.5", "v1.3.0"],
    "timestamp": {
      "created": 1541458026,
      "closed": 1541457010
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/629.console"></div>
<p>During indexing, tokens are created for each leaf value in the JSON object. The
values are indexed as string keywords, without analysis or special handling for
numbers or dates.</p>
<p>Querying the top-level <code class="literal">flattened</code> field searches all leaf values in the
object:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST bug_reports/_search
{
  "query": {
    "term": {"labels": "urgent"}
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/630.console"></div>
<p>To query on a specific key in the flattened object, object dot notation is used:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST bug_reports/_search
{
  "query": {
    "term": {"labels.release": "v1.3.0"}
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/631.console"></div>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="supported-operations"></a>Supported operations<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/mapping/types/flattened.asciidoc">edit</a>
</h3>
</div></div></div>
<p>Because of the similarities in the way values are indexed, <code class="literal">flattened</code>
fields share much of the same mapping and search functionality as
<a class="xref" href="keyword.html" title="Keyword datatype"><code class="literal">keyword</code></a> fields.</p>
<p>Currently, flattened object fields can be used with the following query types:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">term</code>, <code class="literal">terms</code>, and <code class="literal">terms_set</code>
</li>
<li class="listitem">
<code class="literal">prefix</code>
</li>
<li class="listitem">
<code class="literal">range</code>
</li>
<li class="listitem">
<code class="literal">match</code> and <code class="literal">multi_match</code>
</li>
<li class="listitem">
<code class="literal">query_string</code> and <code class="literal">simple_query_string</code>
</li>
<li class="listitem">
<code class="literal">exists</code>
</li>
</ul>
</div>
<p>When querying, it is not possible to refer to field keys using wildcards, as in
<code class="literal">{ "term": {"labels.time*": 1541457010}}</code>. Note that all queries, including
<code class="literal">range</code>, treat the values as string keywords. Highlighting is not supported on
<code class="literal">flattened</code> fields.</p>
<p>It is possible to sort on an flattened object field, as well as perform simple
keyword-style aggregations such as <code class="literal">terms</code>. As with queries, there is no
special support for numerics — all values in the JSON object are treated as
keywords. When sorting, this implies that values are compared
lexicographically.</p>
<p>Flattened object fields currently cannot be stored. It is not possible to
specify the <a class="xref" href="mapping-store.html" title="store"><code class="literal">store</code></a> parameter in the mapping.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="flattened-params"></a>Parameters for flattened object fields<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/mapping/types/flattened.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The following mapping parameters are accepted:</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<a class="xref" href="mapping-boost.html" title="boost"><code class="literal">boost</code></a>
</p>
</td>
<td valign="top">
<p>
Mapping field-level query time boosting. Accepts a floating point number,
defaults to <code class="literal">1.0</code>.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">depth_limit</code>
</p>
</td>
<td valign="top">
<p>
The maximum allowed depth of the flattened object field, in terms of nested
inner objects. If a flattened object field exceeds this limit, then an
error will be thrown. Defaults to <code class="literal">20</code>. Note that <code class="literal">depth_limit</code> can be
updated dynamically through the <a class="xref" href="indices-put-mapping.html" title="Put mapping API">put mapping</a> API.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<a class="xref" href="doc-values.html" title="doc_values"><code class="literal">doc_values</code></a>
</p>
</td>
<td valign="top">
<p>
Should the field be stored on disk in a column-stride fashion, so that it
can later be used for sorting, aggregations, or scripting? Accepts <code class="literal">true</code>
(default) or <code class="literal">false</code>.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<a class="xref" href="eager-global-ordinals.html" title="eager_global_ordinals"><code class="literal">eager_global_ordinals</code></a>
</p>
</td>
<td valign="top">
<p>
Should global ordinals be loaded eagerly on refresh? Accepts <code class="literal">true</code> or
<code class="literal">false</code> (default). Enabling this is a good idea on fields that are
frequently used for terms aggregations.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<a class="xref" href="ignore-above.html" title="ignore_above"><code class="literal">ignore_above</code></a>
</p>
</td>
<td valign="top">
<p>
Leaf values longer than this limit will not be indexed. By default, there
is no limit and all values will be indexed. Note that this limit applies
to the leaf values within the flattened object field, and not the length of
the entire field.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<a class="xref" href="mapping-index.html" title="index"><code class="literal">index</code></a>
</p>
</td>
<td valign="top">
<p>
Determines if the field should be searchable. Accepts <code class="literal">true</code> (default) or
<code class="literal">false</code>.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<a class="xref" href="index-options.html" title="index_options"><code class="literal">index_options</code></a>
</p>
</td>
<td valign="top">
<p>
What information should be stored in the index for scoring purposes.
Defaults to <code class="literal">docs</code> but can also be set to <code class="literal">freqs</code> to take term frequency
into account when computing scores.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<a class="xref" href="null-value.html" title="null_value"><code class="literal">null_value</code></a>
</p>
</td>
<td valign="top">
<p>
A string value which is substituted for any explicit <code class="literal">null</code> values within
the flattened object field. Defaults to <code class="literal">null</code>, which means null sields are
treated as if it were missing.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<a class="xref" href="similarity.html" title="similarity"><code class="literal">similarity</code></a>
</p>
</td>
<td valign="top">
<p>
Which scoring algorithm or <em>similarity</em> should be used. Defaults
to <code class="literal">BM25</code>.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">split_queries_on_whitespace</code>
</p>
</td>
<td valign="top">
<p>
Whether <a class="xref" href="full-text-queries.html" title="Full text queries">full text queries</a> should split the input on
whitespace when building a query for this field. Accepts <code class="literal">true</code> or <code class="literal">false</code>
(default).
</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="histogram.html">« Histogram datatype</a>
</span>
<span class="next">
<a href="geo-point.html">Geo-point datatype »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
